package com.pokermind.repository.dao;

import com.pokermind.model.po.PokerDecisionSnapshot;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

/**
 * PokerDecisionSnapshot DAO接口
 * 定义AI决策快照相关的数据访问操作
 * 
 * @author PokerMind Team
 */
public interface PokerDecisionSnapshotDao extends BaseDao<PokerDecisionSnapshot, Long> {
    
    /**
     * 根据手牌ID查找所有决策快照
     * @param handId 手牌ID
     * @return 决策快照列表，按快照序号排序
     */
    List<PokerDecisionSnapshot> findByHandId(Long handId);
    
    /**
     * 根据用户ID查找决策快照
     * @param userId 用户ID
     * @param limit 返回数量限制
     * @return 决策快照列表，按创建时间倒序
     */
    List<PokerDecisionSnapshot> findByUserId(Long userId, int limit);
    
    /**
     * 根据手牌ID和快照序号查找决策快照
     * @param handId 手牌ID
     * @param snapshotSequence 快照序号
     * @return 决策快照，如果不存在返回empty
     */
    Optional<PokerDecisionSnapshot> findByHandIdAndSequence(Long handId, Integer snapshotSequence);
    
    /**
     * 根据用户ID和时间范围查找决策快照
     * @param userId 用户ID
     * @param startTime 开始时间
     * @param endTime 结束时间
     * @return 决策快照列表
     */
    List<PokerDecisionSnapshot> findByUserIdAndTimeRange(Long userId, LocalDateTime startTime, LocalDateTime endTime);
    
    /**
     * 查找有AI推荐的决策快照
     * @param userId 用户ID（可选，为null时查找所有用户）
     * @param limit 返回数量限制
     * @return 有AI推荐的决策快照列表
     */
    List<PokerDecisionSnapshot> findWithAiRecommendation(Long userId, int limit);
    
    /**
     * 查找高置信度的AI推荐
     * @param userId 用户ID（可选，为null时查找所有用户）
     * @param minConfidence 最小置信度
     * @param limit 返回数量限制
     * @return 高置信度决策快照列表
     */
    List<PokerDecisionSnapshot> findHighConfidenceRecommendations(Long userId, java.math.BigDecimal minConfidence, int limit);
    
    /**
     * 统计用户的决策快照数量
     * @param userId 用户ID
     * @return 决策快照总数
     */
    long countByUserId(Long userId);
    
    /**
     * 统计手牌的决策快照数量
     * @param handId 手牌ID
     * @return 决策快照数量
     */
    long countByHandId(Long handId);
    
    /**
     * 获取用户最新的决策快照
     * @param userId 用户ID
     * @return 最新的决策快照，如果不存在返回empty
     */
    Optional<PokerDecisionSnapshot> findLatestByUserId(Long userId);
    
    /**
     * 删除手牌的所有决策快照
     * @param handId 手牌ID
     * @return 删除的行数
     */
    int deleteByHandId(Long handId);
    
    /**
     * 根据AI推荐类型查找决策快照
     * @param recommendation AI推荐类型
     * @param userId 用户ID（可选）
     * @param limit 返回数量限制
     * @return 决策快照列表
     */
    List<PokerDecisionSnapshot> findByRecommendation(String recommendation, Long userId, int limit);
}